---
description: How to create custom incident forms
---

# Forms

## Creating a custom form

Within Dispatch, admins can create a custom form under Settings -> (choose Project) -> Incident / Form Types. This brings up a table of existing form types (if any). Click on the NEW button to create a new form type.

### Form schema

The form schema takes a JSON array of form objects of the following type:

| Attribute | Possible values             | Notes                             |
| --------- | --------------------------- | --------------------------------- |
| type      | boolean, select, text, date |                                   |
| title     |                             | this is the question              |
| if        |                             | conditional (see below)           |
| name      |                             | unique identifier string          |
| multiple  | true, false                 | only for select                   |
| options   |                             | list of options / only for select |
| hint      |                             | shown as small text (optional)    |

The following fields are required for each form object: `type`, `title`, and `name`. For `select` types, there must be a corresponding `options` attribute.

Note: be sure to set the form type to "Enabled" so that it will appear in the forms tab in the incident.

#### Conditionals

The `if` attribute can be a complex JavaScript boolean expression. Refer to other form items using the format `$<name>` where `<name>` is the unique name identifier.

##### Example

```
   [
     { "type": "boolean", "title": "Is this a good form?", "name": "good_form", "hint": "Check if you like"},
     { "type": "select", "if": "$good_form", "title": "How good?", "options": [ "Very much", "A lot", "It's ok" ], "multiple": false, "name": "like_level"},
     { "type": "text", "if": "$good_form && $like_level && $like_level.includes('A lot')", "title": "Provide more feedback", "name": "feedback"}
   ]
```

## Fill out a form in an incident

After an incident is opened, go to the View/Edit panel and select the Forms tab at the top. This view will list all of the forms that have been filled out so far. They can either be in the Draft or Completed state. Users can either edit an existing form or create a new one based on any of the enabled form types created as above.

While a form is being completed, the user can **Cancel** to discard any changes, **Save as Draft** to save the filled in information and set as _Draft_, or **Submit** to save and set as _Completed_.

## Attorney review

A new tab on the left "Forms" lists all of the _Draft_ and _Completed_ forms for leadership and attorney review. For each form, users can view/edit, delete, and a special **Attorney Review** option. This option shows relevant incident details and the values filled out in the form. It also provides an attorney status dropdown and two new fields for attorney notes and open questions.

## Additional attorney questions

If additional questions are required for the attorney team to assess the information on the form, each form type has the option of asking additional attorney questions. This schema follows the same format as the main form schema. The additional attorney questions will appear only on the Attorney Section when performing the Attorney Review from the Forms page.

![](/img/attorney-section.png)

## Scoring schema

A risk score can be calculated based on the form responses. The scoring schema is a JSON array of objects of the following type:

| Attribute | Type | Notes                                  |
| --------- | ---- | -------------------------------------- |
| var       | text | the corresponding variable on the form |
| includes  | list | a JSON list of chosen options          |
| score     | int  | the score to add                       |

If the form data corresponding to `var` contains any elements in the list `includes`, then the value indicated by `score` is added to the Risk Score. Note that this is currently not cumulative, i.e., if there are two elements on the list in the form data, the score is only added once. For example, using the example form schema above and the below scoring schema, if the user selects "Very much", the risk score would be 10.

```
   [
     { "var": "like_level", "includes": [ "Very much", "A lot" ], "score": 10},
     { "var": "like_level", "includes": [ "It's ok" ], "score": 1},
   ]
```

The risk score shows up on the Forms tab in the Risk Score column as well as on the attorney summary section on the Attorney Review card.

![](/img/example-risk-score.png)
